home *** CD-ROM | disk | FTP | other *** search
/ Aminet 45 / Aminet 45 (2001)(GTI - Schatztruhe)[!][Oct 2001].iso / Aminet / game / role / ldmud-3.2-bin.lha / mud / doc / efun / map < prev    next >
Text File  |  2001-04-06  |  3KB  |  86 lines
  1. SYNOPSIS
  2.         mixed * map(mixed *arg, string func, string|object ob
  3.                                            , mixed extra...)
  4.         mixed * map(mixed *arg, closure cl, mixed extra...)
  5.         mixed * map(mixed *arg, mapping m)
  6.  
  7.         mapping map(mapping arg, string func, string|object ob
  8.                                             , mixed extra...)
  9.         mapping map(mapping arg, closure cl, mixed extra...)
  10.  
  11.  
  12. DESCRIPTION
  13.         Call the function <ob>-><func>() resp. the closure <cl> for
  14.         every element of the array or mapping <arg>, and return a result
  15.         made up from the returned values.
  16.  
  17.         If <ob> is omitted, or neither a string nor an object, it
  18.         defaults to this_object().
  19.  
  20.  
  21.         If <arg> is an array, the function will be called with each
  22.         of the array elements as first parameter, followed by the
  23.         <extra> arguments. The result of the efun is an array with
  24.         all the results returned from the function calls. Thus the
  25.         operation could be described as:
  26.  
  27.           foreach(index) result[index] = ob->func(arg[index], extra...)
  28.  
  29.         If <arg> is an array, and a mapping is specified instead
  30.         of a function, the result is an array with the values found
  31.         in the mapping for the original values, resp. with the original
  32.         values for which no mapping entry exists. In other words:
  33.  
  34.           foreach(index)
  35.              if (arg[index] exists as key in map)
  36.                  result[index] = map[arg[index]]
  37.              else
  38.                  result[index] = arg[index]
  39.  
  40.  
  41.         If <arg> is a mapping, the function will be called with
  42.         each of the mapping keys as first, and (if existing) the
  43.         associated values as second parameter, followed by the <extra>
  44.         arguments (these must not be protected references like &(i[0]). The
  45.         result of the efun is a mapping of all results of the function calls,
  46.         stored under their corresponding key.
  47.  
  48.         Depending on the width of the mapping <arg>, the operation can
  49.         be described as:
  50.  
  51.           foreach (key in arg)
  52.             switch (widthof(arg))
  53.             case 0:
  54.               result[key] = ob->func(key, 0, extra...)
  55.             case 1:
  56.               result[key] = ob->func(key, arg[key], extra...)
  57.             else  :
  58.               result[key] = ob->func( key
  59.                                     , ({ arg[key,0] ...arg[key,width-1] })
  60.                                     , extra...)
  61.  
  62.         The advantage of this approach is that the two types of
  63.         multi-dimensional mappings (mappings with multiple values
  64.         per key, and mappings of arrays) can be treated in the same way.
  65.  
  66.  
  67.         Note that map() used with arrays behaves like map_array(), but used
  68.         with mappings generalises map_indices()!
  69.  
  70.  
  71. EXAMPLES
  72.         arr = ({ 1, 2, 3, 4 });
  73.         m = ([ 1:-1, 3:-3 ]);
  74.  
  75.         map(arr, #'%, 2)  --> returns ({ 1, 0, 1, 0 })
  76.         map(arr, m)       --> returns ([ -1, 2, -3, 4 })
  77.  
  78.  
  79. HISTORY
  80.         Introduced in LDMud 3.2.6, obsoletes map_array().
  81.         LDMud 3.2.8 added the feature of mapping an array through a mapping.
  82.  
  83. SEE ALSO
  84.         filter(E), filter_indices(E), map_indices(E), map_objects(E)
  85.  
  86.